---
title: Deployment Service
description: Durable deployment workflow orchestration
---

# Deployment Service

The `DeploymentService` orchestrates the complete deployment lifecycle, from building containers to assigning domains.

**Location:** `go/apps/ctrl/workflows/deploy/`
**Proto:** `go/proto/hydra/v1/deployment.proto`
**Key:** `project_id`

## Operations

### Deploy

<Mermaid chart={`flowchart TD
    Start([Deploy Request]) --> FetchMeta[Fetch Metadata]
    FetchMeta --> StatusBuilding[Status: Building]
    StatusBuilding --> CreateKrane[Create in Krane]
    CreateKrane --> PollStatus{Poll Until Ready}
    PollStatus --> UpsertVMs[Upsert VM Records]
    UpsertVMs --> PollStatus
    PollStatus --> ScrapeAPI[Scrape OpenAPI Spec]
    ScrapeAPI --> BuildRoutes[Build Ingress Routes]
    BuildRoutes --> AssignRoutes[Call RoutingService]
    AssignRoutes --> StatusReady[Status: Ready]
    StatusReady --> UpdateLive[Update Live Deployment]
    UpdateLive --> End([Complete])

    style AssignRoutes fill:#e1f5fe
    style StatusReady fill:#c8e6c9
`} />

Creates a new deployment:
1. Fetch deployment, workspace, project, environment metadata
2. Create deployment in Krane
3. Poll until instances are running
4. Scrape OpenAPI spec
5. Call RoutingService to assign ingress routes atomically
6. Update project's live deployment ID

Implementation: `go/apps/ctrl/workflows/deploy/deploy_handler.go`

### Rollback

<Mermaid chart={`flowchart TD
    Start([Rollback Request]) --> Validate[Validate Deployments]
    Validate --> CheckVMs[Check Target VMs]
    CheckVMs --> FindRoutes[Find Sticky Ingress Routes]
    FindRoutes --> UpdateRoutes[Update Route Deployment IDs]
    UpdateRoutes --> UpdateProject[Update Live Deployment]
    UpdateProject --> End([Success])

    style UpdateRoutes fill:#e1f5fe
    style UpdateProject fill:#c8e6c9
`} />

Rolls back to a previous deployment:
1. Validate source/target deployments
2. Find sticky ingress routes (live + environment level)
3. Update ingress routes to point to target deployment
4. Update project metadata

Implementation: `go/apps/ctrl/workflows/deploy/rollback_handler.go`

### Promote

<Mermaid chart={`flowchart TD
    Start([Promote Request]) --> Validate[Validate Deployment]
    Validate --> FindRoutes[Find All Ingress Routes]
    FindRoutes --> UpdateRoutes[Update Route Deployment IDs]
    UpdateRoutes --> UpdateProject[Update Live Deployment]
    UpdateProject --> End([Success])

    style UpdateRoutes fill:#e1f5fe
`} />

Promotes a deployment to live, removing rolled-back state:
1. Validate deployment is ready
2. Find all project ingress routes
3. Update ingress routes to point to new deployment
4. Clear rolled_back flag

Implementation: `go/apps/ctrl/workflows/deploy/promote_handler.go`

## Why RoutingService?

All ingress route operations are delegated to `RoutingService` to:
- Ensure atomic updates to routing configuration
- Serialize ingress route operations per project
- Provide rollback capabilities for failed routing changes
